DVIPS
Section: User Commands (1)
Updated: 5 January 1990
Index
Return to Main Contents
NAME
dvips - convert a TeX DVI file to PostScript (PostScript is a
trademark of Adobe Systems, Inc.)
SYNOPSIS
dvips
[
-c
num
]
[
-d
num
]
[
-e
num
]
[
-f
]
[
-h
file
]
[
-m
]
[
-n
num
]
[
-o
file
]
[
-p
num
]
[
-q
]
[
-r
]
[
-s
str
]
[
-t
modename
]
[
-x
num
]
[
-C
num
]
[
-D
num
]
[
-F
]
[
-N
]
[
-P printername
]
[
-Z
]
[
-?
]
file[.dvi]
DESCRIPTION
The program
dvips
converts a DVI file
file[.dvi]
produced by TeX (or by some other processor like GFtoDVI)
and converts it to PostScript, normally
sending the result directly to the laserprinter.
The result requires a small amount of
PostScript source to precede it, before it can be successfully printed.
By default, that PostScript code is prepended to the output.
If no file
is specified in the command line, the DVI file is read from the standard
input stream.
The DVI file may be specified without the
.dvi
extension.
Fonts used may either be resident in the printer or defined as bitmaps
in PK files, or a `virtual' combination of both.
If the
MakeTeXPK
program is installed,
dvips
will automatically invoke METAFONT to generate fonts that don't already exist.
OPTIONS
Boolean flags that are turned on by
certain letters (such as -r to reverse pages) can be turned off
by following the option immediately with a 0 (as in -r0). The
options that this can be used with are fmqrFNZ.
The command line switches are:
- -c num
-
Generate
num
copies of every page.
Default is 1. (For collated copies, see the
-C
option below.)
- -d num
-
Set the debug flags.
This is intended only for emergencies or for unusual
fact-finding expeditions; it will work only if
dvips
has been compiled with the DEBUG option.
The file
debug.h
in the sources indicates what the values of
num
can be.
- -e num
-
Make sure that each character is placed at most this many pixels from its
`true' resolution-independent
position on the page. The default value of this parameter
is resolution dependent (it is the number
of entries in the list [100, 200, 300, 400, 500, 600, 800, 1000, 1200, 1600,
2000, 2400, 2800, 3200, ...] that are less than or equal to the resolution in
dots per inch). Allowing individual
characters to `drift' from their correctly rounded positions
by a few pixels, while regaining the true position at the beginning of
each new word, improves the spacing of letters in words.
- -f
-
Run as a filter.
Read the DVI file from standard input and write the PostScript to
standard output.
- -h name
-
Prepend file
name
as an additional header file. (However, if the name is simply `-',
suppress all header files from the output.)
- -m
-
Specify manual feed for printer.
- -n num
-
At most
num
pages will be printed out.
Default is 100000.
- -o name
-
The output will be sent to file
name.
If no file name is given, the default name is
file.ps;
if this option isn't given, the default name is !lpr.
If the first character of the file name is an exclamation mark, then
the remainder will be used as an argument to popen; thus, specifying
!lpr as the output file will automatically queue the file for printing.
- -p num
-
The first page printed will be the first one numbered
num.
Default is the first page in the document.
- -q
-
Run in quiet mode.
Don't chatter about pages converted, etc.; report nothing but errors to stderr.
- -r
-
Stack pages in reverse order.
Normally, page one will be printed first.
- -t modename
-
This sets the mode to modename.
Currently, the only modes allowable are:
letter, which selects letter size (8.5 by 11 inch page);
a4, which selects a4 size;
legal, which selects legal size (8.5 by 14 inches);
landscape, which rotates
a letter size document by ninety degrees.
The default mode is letter. The upper left corner of each page in
the DVI file is placed one inch from the left and one inch from the top.
- -x num
-
Set the magnification ratio to
num
/1000. Overrides the magnification specified in the DVI file.
Must be between 10 and 100000.
- -C num
-
Create
num
copies, but collated (by replicating the data in the PostScript file).
Slower than the
-c
option, but easier on the humans.
- -D num
-
Set the resolution in dpi (dots per inch) to
num.
This affects the choice of bitmap fonts that are loaded and also the positioning
of letters in resident PostScript fonts. Must be between 10 and 10000.
- -F
-
Causes control-D (ASCII code 4) to be appended as the very last character
of the PostScript file.
- -N
-
Turns off structured comments; this might be necessary on some systems
that try to interpret PostScript comments in weird ways.
- -P printername
-
Sets up the output for the appropriate printer. This is implemented
by reading in
config.printername,
which can then set the output pipe
(as in, !lpr -Pprintername) as well as the font paths and any other
defaults for that printer only. It is recommended that all standard
defaults go in the one master
config.ps
file and only things that vary
printer to printer go in the
config.printername
files. Note that
config.ps
is read before
config.printername.
- -Z
-
Causes bitmap fonts to be compressed before they are downloaded,
thereby reducing the size of the PostScript font-downloading information
to about 70% of the uncompressed size. Especially useful at high resolutions.
- -?
-
Print out the banner identifying the program.
CONFIG FILE OPTIONS
The file
config.ps
can be used to set many of the options to configure
dvips
for a particular site.
These will probably be set by the installer, so normal users can skip
this section.
The name and location of the config file can be changed at installation time.
Each line of the file specifies a configuration option.
If the initial
character is a space, an asterisk, a pound sign, or a semicolon,
the line is ignored.
But if the initial character is an option like "o", for example,
the remainder of the line is considered to be the default file output
name (e.g. /dev/lpr).
The options are:
- D num
-
Sets the resolution to
num
dots per inch (dpi).
- e num
-
Sets the maximum drift parameter to
num
dots (pixels) as explained above.
- m num
-
num
is the virtual memory available for fonts and strings in the printer.
Default is 180000.
- o name
-
The default output file is set to
name.
- t path
-
The (colon-separated) path to search for the tfm files is
path.
The TEXFONTS environment variable will override this. This path is used for
resident fonts and fonts that can't be otherwise found. It's usually best to
make it identical to the path used by TeX.
- v path
-
The (colon-separated) path to search for virtual font (VF) files is
path.
This may be device-dependent, if you use virtual fonts to simulate
actual fonts on different devices.
- p path
-
The (colon-separated) path to search for bitmap (PK) font files is
path.
The TEXPKS environment variable will override this.
- s path
-
The (colon-separated) path to search for special illustrations
(encapsulated PostScript files or psfiles) is
path.
The TEXINPUTS environment variable will override this.
- r
-
Reverse the order of pages by default.
- q
-
Run in quiet mode by default.
- f
-
Run as a filter by default.
- h name
-
Add
name
as a PostScript header file to be downloaded at the beginning.
- M mode
-
Set
mode
as the METAFONT mode to be used when generating fonts. This is
passed along to MakeTeXPK and overrides mode derivation from the
base resolution.
- N
-
Disable PostScript comments by default.
- Z
-
Compress all downloaded fonts by default.
POSTSCRIPT FONT SUPPORT
This version of dvips supports PostScript fonts.
You need TFM (TeX Font Metric) files for all fonts seen by TeX; they
can be generated from AFM (Adobe Font Metric) files
by running the program
afm2tfm
(which is described on its own manual page). That program also creates
virtual fonts with which you can use normal plain TeX conventions.
The set of all resident fonts known to
dvips
appears in the file
psfonts.map,
which should be updated whenever you install a new resident font. See
afm2tfm
for examples.
\special OPTIONS
This DVI driver allows the inclusion of PostScript code
to be inserted in a TeX file via TeX's \special command.
For compatibility with other systems, several different conventions
are supported.
First, there's a flexible key-and-value scheme:
\special{psfile="filename"[ key=value]*}
This will download the PostScript file called
filename
such that the current point will be the origin of the PostScript
co-ordinate system.
The optional key/value assignments allow you
to specify transformations on the PostScript in
filename.
The possible keys are:
hoffset The horizontal offset (default 0)
voffset The vertical offset (default 0)
hsize The horizontal clipping size (default 612)
vsize The vertical clipping size (default 792)
hscale The horizontal scaling factor (default 100)
vscale The vertical scaling factor (default 100)
angle The rotation (default 0)
The hoffset, voffset, hsize, and vsize are given in PostScript units
(1/72 of an inch), called bp elsewhere in TeX; these are the units of the
default coordinate system assumed to be valid in the PostScript file.
The hscale and vscale are given in non-dimensioned percentage units, and the
rotate value is specified in degrees.
Thus
\special{psfile=foo.ps hoffset=72 hscale=90 vscale=90}
will shift the graphics produced by file
foo.ps
right by 1", and will
draw it at 0.9 normal size.
If either hsize or vsize is specified, the figure will be clipped to a
rectangular region from (0,0) to (hsize,vsize) in default coordinates,
after scaling, translation, and/or rotation. Otherwise no clipping will be done.
Offsets are given relative to the point of the \special command, and are
unaffected by scaling or rotation. Rotation is counterclockwise about (0,0).
The order of operations is: Take the PostScript figure, rotate it, then
scale it, then offset it, then clip it. For example, if you want to extract
a one-inch-square figure bounded by (100,200), (172,200), (172,272), and
(100,272) in the PostScript coordinates of the graphic in cropthis.ps,
you would say
\special{psfile=cropthis.ps hoffset=-100 yoffset=-200 hsize=72 vsize=72}
Secondly, if your file conforms to the
Encapsulated Post Script
(EPS) conventions, then it is possible to use a simpler
\special
command that will automatically reserve the required space.
To use, simply say
\input epsf % at the beginning of your TeX document
\epsfbox{filename.ps} % at the place where you want the figure
A
vbox
of the appropriate size for the bounding box will be built. The
height and width of this vbox will be the height and width of the figure;
the depth of the vbox will be zero.
By default, the graphic will have its `natural' width.
If you wish to enlarge or reduce it,
simply set the dimension `\epsfxsize'
to something else, such as `\hsize'; the figure will be scaled so that
\epsfxsize is its final width.
This vbox can be centered with \centerline, or treated as any other vbox.
(The \epsfbox macro does its job by scanning filename.ps for a standard
`BoundingBox' comment. The figure is clipped to the size of that bounding
box. If no bounding box is found, the coordinates `72 72
If the bounding box is not found, a bounding box of `72 72 540 720' is
assumed.
If the PostScript file to be included is not EPSF, you are probably better
off using the
psfile
special instead.)
Thirdly, there are special commands for drawing diagrams using the conventions
of `TPIC' (a portable, non-PostScript-dependent program by Tim Morgan,
with PostScript implementation by Dorab Patel). For example,
`\special{pn 2}' in this language sets the pen size to .002 inch.
A fourth type of \special allows you to write PostScript instructions that
will be passed literally to dvips's output file. These are intended for
people whose favorite graphics language is raw PostScript.
\special{" text}
includes
text
literally in the output PostScript document,
after translating the origin to the current page position, opening a
special user dictionary, and
and reverting to the PostScript convention of 72 units=1in.
\special{! text}
includes
text
literally in the prolog (before all typesetting is done), putting
definitions in the special dictionary; this is good for definitions you intend
to use with \special{"}.
Note that
dvips
will always include such specials
in the prolog, unless they occur on pages after the last page printed.
This allows correct printing of selected pages,
even when literal PostScript definitions are used, provided that
you give definitions before their first use.
A fifth type of \special allows literal PostScript instructions to be
inserted
without
enclosing them in an invisible protective shield; users of this feature
are supposed to understand what they are doing (and they shouldn't change
the PostScript graphics state unless they are willing to take the
consequences). This command can take many forms, because it has had a
tortuous history; any of the following will work:
\special{ps:text}
\special{ps::text}
\special{ps::[begin]text}
\special{ps::[end]text}
(with longer forms taking precedence over shorter forms, when they are used).
Exception: The command
will copy the commands from
filename
verbatim into dvips's output (but omitting lines that begin with %).
An example of the proper use of literal specials can be found in the file
rotate.tex, which makes it easy to typeset text turned 90 degrees.
Finally, there are two special cases of \special, which provide
alternatives to certain dvips command-line options: (1) You may put the command
\special{landscape}
anywhere in your document (except after the final page selected for
printing), and the entire document will be printed in landscape mode.
(2) The command
\special{header=
filename}
may be used to add
filename
as a header file (i.e., a file that will be downloaded before the
start of processing).
This is usually used for Macintosh header files.
FILES
Files used by dvips are usually system dependent, but the following are typical:
the prolog dir /usr/lib/tex/ps
the config dir /usr/lib/tex/ps
the tfm dir /usr/lib/tex/fonts/tfm
the font dir /usr/lib/tex/fonts/pk
the virtual font dir /usr/lib/tex/fonts/vf
the epsf/psfile dir .:/usr/lib
SEE ALSO
mf(1), afm2tfm(1), tex(1), latex(1), lpr(1)
BUGS
Rejects any file with the string "IBM" in it.
This is considered to be a feature by some.
AUTHOR
Tomas Rokicki <rokicki@neon.stanford.edu>; extended to virtual fonts
by Don Knuth.
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- OPTIONS
-
- CONFIG FILE OPTIONS
-
- POSTSCRIPT FONT SUPPORT
-
- \special OPTIONS
-
- FILES
-
- SEE ALSO
-
- BUGS
-
- AUTHOR
-
This document was created by
man2html,
using the manual pages.
Time: 23:58:48 GMT, December 11, 2024